Release 10.1A: OpenEdge Development:
Progress 4GL Reference

ProDataSet events

Progress provides events you can invoke to execute application-specific code that handles FILL operations on a ProDataSet object or Buffer object, as well as row-level change operations. You can use the SET-CALLBACK-PROCEDURE( ) method to associate an action with these events.

Event procedures must define a single parameter for the ProDataSet object (DATASET or DATASET-HANDLE) as an INPUT parameter BY-REFERENCE. This allows the event procedure to operate on the ProDataSet object using static 4GL to reference its buffers and fields, without the ProDataSet object being physically copied. This also means that because the ProDataSet object is not copied, changes made to the ProDataSet object by the event procedure are made to the same copy used by all procedures.

The following sections describe the ProDataSet events:

FILL events
Row-level events
OFF-END event
FIND-FAILED event
SYNCHRONIZE event

FILL events

There are two levels of FILL events: the first level is for a ProDataSet object or one of its member buffer objects; the second level is for individual records created in each temp-table.

Table 101 lists the first-level FILL events.

Table 101: First-level FILL events 

Event	Affected objects	Progress action
AFTER-FILL	Buffer object of a DATASET temp-table, ProDataSet object.	This event occurs at the very end of a FILL, and can be used to adjust the contents of the ProDataSet object or Buffer object, reject the FILL operation, or disconnect from a server or database. For a child table, the event occurs once for each parent record that is created.
BEFORE-FILL	Buffer object of a DATASET temp-table, ProDataSet object.	This event occurs at the very beginning of a FILL, before anything is read or created. For a Buffer object, this event allows the developer to do preparatory work for an individual table. For the parent table in a set of related tables, where the FILL event is applied to this top-level table, it could be the same kind of connection code as for the ProDataSet object as a whole. For a child table, the event occurs once for each parent record that is created, and allows the developer to adjust the query for the child table, or cancel the FILL for that parent altogether. For a ProDataSet object, this event allows the developer to make a server or database connection, or do other preparatory work. Alternatively, it allows the developer to intercept and fully replace the default behavior.

Table 102 lists the second-level FILL events. These events occur once immediately before or after each record is created in a temp-table during a FILL.

Table 102: Second-level FILL events 

Event	Affected objects	Progress action
AFTER-ROW-FILL	Buffer object of a DATASET temp-table.	This event occurs after a record is created in the temp-table. The procedure can, for example, modify field values in the record by supplying values for calculated fields, or perform filtering and reject a record by deleting it. The procedure cannot modify record currency using the ProDataSet object buffers in any other way. It can use separately defined buffers to modify the ProDataSet object in other ways. The procedure can RETURN ERROR to abort the entire FILL, or RETURN NO-APPLY to cancel the cascading of the FILL to child buffers, if any.
BEFORE-ROW-FILL	Buffer object of a DATASET temp-table.	This event occurs before a record is created in the temp-table, but after the data source record(s) for it are read. For example, this procedure could examine the database buffers or other information and decide not to create the record, using a RETURN NO-APPLY statement.

Row-level events

Row-level events are defined for making local changes to the records in a ProDataSet member buffer object.

Table 103 lists the row-level events.

Table 103: Row-level events

Event	Affected objects	Progress action
ROW-CREATE	Buffer object of a DATASET temp-table.	This event occurs immediately after the record is created in the temp-table. The current buffer for the temp-table is available and contains initial values as defined in the temp-table definition (or inherited from the schema). You can use this event to calculate initial values for fields, make changes to other records, or reject the creation by deleting the new temp-table record.
ROW-DELETE	Buffer object of a DATASET temp-table.	This event occurs when you delete a temp-table record, immediately before the record is deleted. The event procedure can use this event to RETURN ERROR to cancel the delete, or to make adjustments to other records based on the delete. Since the record has not yet been deleted, the record is in the temp-table buffer and the code can look at its values. Because the code can assume that the DELETE will go through unless cancelled by the event procedure itself, it can take actions based on the record deletion while the record is still there to be looked at.
ROW-UPDATE	Buffer object of a DATASET temp-table.	This event occurs immediately before the record is updated in the temp-table. It typically occurs when: The buffer scope ends. The transaction scope ends. The RELEASE statement or BUFFER-RELEASE( ) method is run on the buffer. The buffer is needed for another record. Progress sets the SELF system handle to the handle of the buffer on which the event procedure is running before calling the event handler. If the event handler returns NO-APPLY or ERROR, the return is ignored. The handler has run, and it is too late to undo any changes to the record. You can use this event to determine if and how a record has changed by reading the buffer in the before-image table (using the SELF:BEFORE-ROWID attribute) and comparing it to the updated buffer. You can also use this event in the event handler to update fields in the record (for example, to supply a calculated field). You cannot read another record into the buffer on which the event procedure is running in the event handler. If you need to read another record, use a different buffer to avoid disturbing the record you are currently updating.

OFF-END event

The OFF-END event occurs when you position a query on a ProDataSet temp-table buffer past the last row. You can use this event to retrieve additional data source rows to add at the bottom of a ProDataSet temp-table (for example, in batches when there are too many data source rows to retrieve at one time).

The OFF-END event can also occur when the user performs a keyboard or mouse action in a browse that scrolls off the end (past the last row) of a browse on a ProDataSet temp-table buffer. For more information about using the OFF-END event with a browse, see the "High-level widget events" section.

Note: The OFF-END event is similar to the QUERY-OFF-END attribute, which is set to TRUE whenever the associated query object is positioned past the last row. The difference is that you must test the QUERY-OFF-END attribute for this condition at a specific place in your application code, whereas the OFF-END event procedure executes like a trigger whenever the event occurs.

Consider the following restrictions when using the OFF-END event with a query on a ProDataSet temp-table buffer:

You can attach these events only to a query on a single ProDataSet temp-table buffer. You cannot attach these events to a query on a database buffer, or a query that involves a join.
The query must be a scrolling query.
If you never RETURN NO-APPLY, from the OFF-END event handler, the query will infinitely loop.
Call the SET-CALLBACK-PROCEDURE( ) method before the query is opened.
If you use the GET LAST statement or GET-LAST( ) method to get the last record associated with the query, the event handler is called repeatedly until it does not RETURN NO-APPLY (indicating that all records have been retrieved). For this reason, use caution when offering users the GET LAST action.
The INDEXED-REPOSITION option is ignored for the query.

FIND-FAILED event

The FIND-FAILED event occurs when a FIND on a ProDataSet temp-table buffer fails. This can be the result of the FIND statement (but not the FIND NEXT, FIND PREV, or FIND LAST statements, and not the CAN-FIND function), or the FIND-FIRST( ) or FIND-UNIQUE( ) methods (but not on the FIND-LAST( ) method).

You can use this event to adjust the contents of the ProDataSet object. The event handler must be able to determine the action to take based on the context of the ProDataSet object, and must RETURN NO-APPLY to indicate the action was successful. For example, when the event occurs, the event handler could retrieve a missing row or a set of related rows from the server automatically.

SYNCHRONIZE event

The SYNCHRONIZE event occurs when a ProDataSet temp-table buffer is synchronized. That is, when the SYNCHRONIZE( ) method is run on the buffer or a parent buffer, or the buffer is selected in a browse. The event handler is invoked recursively at every level of the ProDataSet object hierarchy just before the recursion to the child levels.

By default, if the query is associated with a browse, the synchronize action of reopening the query automatically refreshes the browse. If the query is not associated with a browse, the synchronize action automatically gets the first row in the query by invoking a GET FIRST operation. If there is a REPOSITION data relation and no browse, the synchronize action gets the next record in the query by invoking a GET NEXT operation. Once these actions attempt to populate the buffer at a particular level, the SYNCHRONIZE event runs before moving recursively to the next lower level.

This event allows you to fetch rows, display buffer values in a frame, or take some other action. The handler procedure can also RETURN NO-APPLY to cancel the cascading of the synchronization to child buffers.